Skip to main content

SSO Authentication

Flow​

Access token flow diagram

  1. When the application starts, authentication service provider identification is checked.
  2. The local storage of browser is checked to have a Refresh Token for the current user.
  3. If Refresh Token exists, Silent Token Update is performed to obtain a new Access Token.
  4. If Silent Token Update fails for any reason, the user will be logged out and redirected to a Login page.
  5. Application back-end uses auth provider to validate access tokens.

Basic Configuration​

This is the example of a common configuration for SSO authentication. Further in text, you can find examples of configurations for selected auth service providers.

# example of SSO common configuration
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <issuer uri>
security:
  oauth2:
    provider:
      providerType: SSO
      name: <name>
      clientId: <client id>
      audience: <audience>
      jwksUrl: <jwks url>
      configUrl: <config url>
      logoutUrl: <logout url>
      usernameClaim: <username claim>
      permissionsClaim: <permissions path claim>
      validateIssuer: <true|false>
      rolesMapping:
        <external role>: [<authority>, ...]
      userInfo:
        enable: <true|false>
        userInfoUrl: <user info url>
        usernameKey: <list of username keys>
ParameterDescription
issuer-uriURI of the auth service provider.
nameName of the auth service provider.
clientIdEach connected application is given a personal ClientId from the provider.
audienceUnique identifier of the audience for an issued token, identified within a JSON Web Token as the audclaim. Each connected back-end (API) is given a personal audience from the auth provider. audience is always associated with a specific auth provider and may be optional with some providers.
jwksUrlURL of the authorization server's JWK Set document. The referenced document contains the signing key(s) the client uses to validate signatures from the authentication server.
configUrlStandard service provider endpoint.
logoutUrlStandard service provider logout URL.
usernameClaimUsername claim in token.
permissionsClaimAuthorities claim in token.
validateIssuerSet true to enable validation of auth provider URL in token against issuer-uri.
rolesMappingOptional map that translates roles received from the auth provider in the permissionsClaim into TimeBase authorities (TB_ALLOW_READ, TB_ALLOW_WRITE, GRAFANA, etc.), so you don't have to rely on how the provider names its roles. See Role Mapping for details.
userInfo.enableSet true to enable user info URL by auth service provider.
userInfo.userInfoUrlURL with information about the user provided by the auth service provider.
userInfo.usernameKeyDefault usernames claims in token from auth service provider.

User Configuration​

Some SSO auth providers allow defining permissions for users and passing them in permissionsClaim.

info

Refer to Configuration to learn how to add or override the default configuration.

# example of configuring user roles via permissions claim from auth provider
security:
  oauth2:
    provider:
      providerType: SSO
      name: <name>
      clientId: <client id>
      audience: <audience>
      jwksUrl: <jwks url>
      configUrl: <config url>
      logoutUrl: <logout url>
      usernameClaim: <username claim>
      permissionsClaim: <permissions path claim>

If your SSO auth provider does not support this, you can define permissions for users in application.yaml config in section users or in a JSON file.

# example of how to define permissions for users for SSO authentication

security:
  oauth2:
    users:
      - username: <username>
        authorities: [TB_ALLOW_READ, TB_ALLOW_WRITE]
      - username: <username>
        authorities: [TB_ALLOW_READ]
...

Supported permissions:

  • TB_ALLOW_READ - user can select, view, get data stored in TimeBase streams.
  • TB_ALLOW_WRITE - user can write, modify, delete data stored in TimeBase streams.
  • GRAFANA - permission allowing Grafana plugin to query data from TimeBase.

You can combine permissions claim from auth provider and custom configurations in one config:

# example of a combination of permissionsClame and custom user configuration
security:
  oauth2:
    users:
      - username: <username>
        authorities: [TB_ALLOW_READ, TB_ALLOW_WRITE]
      - username: <username>
        authorities: [TB_ALLOW_READ]
    provider:
      providerType: SSO
      name: <name>
      clientId: <client id>
      audience: <audience>
      jwksUrl: <jwks url>
      configUrl: <config url>
      logoutUrl: <logout url>
      usernameClaim: <username claim>
      permissionsClaim: <permissions path claim>

Role Mapping​

caution

Role Mapping configuration is available starting from TimeBase WebAdmin 1.2.180.

Instead of (or in addition to) hardcoding usernames under security.oauth2.users, you can let TimeBase translate the roles that your SSO provider (for example, WorkOS) sends in the permissionsClaim into TimeBase authorities. This is configured with rolesMapping, a map where each key is a role name coming from the provider and the value is a list of authorities it should be translated to.

# example of mapping external roles to TimeBase authorities
security:
  oauth2:
    provider:
      providerType: SSO
      name: <name>
      clientId: <client id>
      audience: <audience>
      jwksUrl: <jwks url>
      configUrl: <config url>
      logoutUrl: <logout url>
      usernameClaim: <username claim>
      permissionsClaim: roles
      rolesMapping:
        tb_allow_read: [TB_ALLOW_READ]
        tb_allow_write: [TB_ALLOW_WRITE]
        org-tb_allow_read: [TB_ALLOW_READ]
        org-tb_allow_write: [TB_ALLOW_WRITE]
        # one role -> several authorities
        admin: [TB_ALLOW_READ, TB_ALLOW_WRITE]
        # several roles -> one authority
        grafana: [GRAFANA]
        auditor: [GRAFANA]
        # role with no permissions
        blocked: []

Behavior rules:

ScenarioResult
Role is present in rolesMappingIt is replaced with the list of authorities from the mapping (can be 0, 1, or several authorities).
Role is not present in rolesMappingThe role is used as an authority as-is (identity passthrough).
rolesMapping is not set or is emptyAll roles from permissionsClaim pass through unchanged.
Role value contains a comma (e.g. "admin,trader")The value is first split into separate roles, and each one is mapped independently.
Authorities parsed from the standard OAuth2 scope/scp claimNever affected by rolesMapping, even if a mapping key happens to match a SCOPE_* authority. Only roles read from permissionsClaim participate in role mapping.

Configuration Examples for Selected Auth Providers​

ORY Hydra​

To enable SSO with ORY Hydra, add the following blocks to your application.yaml configuration file.

# example of configuration for ORY Hydra
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <service provider uri>

security:
  oauth2:
    provider:
      providerType: SSO
      name: hydra
      clientId: <client_id>
      validateIssuer: false
      userInfo:
        enable: true

Amazon Cognito​

To enable SSO with Amazon Cognito, add the following blocks to your application.yaml configuration file.

# example of configuration for Amazon Cognito
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <service provider uri>

security:
  oauth2:
    provider:
      providerType: SSO
      name: cognito
      clientId: <client_id>
      audience: <audience>
      configUrl: <service provider config url>
      logoutUrl: <service provider logout url>
      usernameClaim: username
      validateIssuer: true

Keycloak​

To enable SSO with Keycloak, add the following blocks to your application.yaml configuration file.

# example of configuration for Keycloak
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <service provider uri>

security:
  oauth2:
    provider:
      provider-type: SSO
      name: keycloak
      clientId: <client_id>
      usernameClaim: preferred_username
      validateIssuer: false
      validateClientId: true

Auth0​

To enable SSO with Auth0, add the following blocks to your application.yaml configuration file.

# example of configuration for Auth0
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <service provider uri>

security:
  oauth2:
    provider:
      providerType: SSO
      name: auth0
      clientId: <client_id>
      audience: <audience url>
      configUrl: <configuration url>
      logoutUrl: <logout url>

Azure AD (Entra ID)​

To enable SSO with Azure AD:

  1. Configure Azure AD (Entra ID) application.

  2. Add the following blocks to your application.yaml configuration file.

# example of configuration for Azure AD
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <azure ad issuer uri> # for example, "https://login.microsoftonline.com/11111111-1111-1111-1111-1111111111111/v2.0"

security:
  oauth2:
    provider:
      providerType: SSO
      name: azure
      clientId: <SPA Application (client) ID>     # from Overview page of p.4.4, ex. 22222222-2222-2222-2222-222222222222
      validateIssuer: true                        # `true` for tokens with version 2 (configured in p 4.5). Set `false` for v1 tokens
      audience: <Service Application ID>          # application ID created in p.3. (skip this field for v1 tokens)l
      usernameClaim: preferred_username 
      scopes:
        - openid
        - profile
        - offline_access
        - <API Permission>                        # from p. 4.3 of Azure AD configuration, ex. api://timebase/webapp

WorkOS​

To enable SSO with WorkOS:

  1. Configure the WorkOS application.

  2. Add the following blocks to your application.yaml configuration file. WorkOS returns role identifiers as lowercase, provider-defined strings (e.g. admin, viewer), so Role Mapping is typically used to translate them into TimeBase authorities.

# example of configuration for WorkOS
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: <Domain to use for AuthKit, a hosted authentication UI by WorkOS>

security:
  oauth2:
    provider:
      providerType: SSO
      name: workos
      clientId: <Connect Application (client) ID>     # from Connect -> Application details page, ex. client_011X111X11ZY11X1111X111YY1
      validateIssuer: true
      permissionsClaim: roles
      usernameClaim: sub
      rolesMapping:
        <workos_role1>: [<authority1>, <authority2>]
        <workos_role2>: [<authority>]

User Access Control with TimeBase Permissions​

Web Admin offers the capability to configure User Access Control (UAC) with permissions derived from the TimeBase server. Each user gets a unique connection to the TimeBase server and can only work with the streams they have permissions for.

Additionally, a "master connection" to TimeBase is created for executing system-level tasks such as processing views, metrics, etc.

Configuration​

To configure user access control with permissions from TimeBase:

  1. Configure TimeBase UAC with OAuth2 for a given authentication provider.
  2. Using the examples above, configure WebAdmin SSO UAC for the same authentication provider and add users.
  3. In the Web Admin's application.yaml file, configure authentication for the master connection to TimeBase:
# example of TimeBase Master connection configuration for Azure AD:
timebase:
  oauth2-client:
    url: https://login.microsoftonline.com/b41b72d0-4e9f-4c26-8a69-f949f367c91d/oauth2/v2.0/token
    client-id: 4d69eb9b-e7c3-4bf3-abc3-5c3ad64cb6fc
    client-secret: UlRzOFF+cXo0SW9pdlJXTU5TdVZBWEZ2OWtZTDhXZ0NDUExlMGFTMQ==
    scope: "api%3A%2F%2Ffcf8a41f-bf18-4229-8a2e-ec84d94df340%2F.default"
  1. In the same file, enable UAC with TimeBase permissions:
timebase:
  enable-uac: true              # Enable TimeBase provided UAC

You can also configure the Web Admin to create a separate TimeBase connection for separate IPs:

timebase:
  uac:
    connection-per-ip: false    # Enable this

Configuration Example for Azure AD​

To configure user access control with TimeBase permissions for Azure AD:

  1. In the uac-oauth-security.xml file, configure TimeBase UAC by adding the users and client id taken from the Web Admin's master connection:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<config xmlns="http://xml.deltixlab.com/internal/quantserver/3.0">
    <users>
        <!-- WebAdmin master connection user (client id) -->
        <user id="4d69eb9b-1111-1111-1111-5c3ad64cb6fd">
        </user>
        
        <!-- Users -->
        <user id="User@mail.com">
        </user>
    </users>
    <groups>
        <group id="Administrators">
            <!-- Add WebAdmin master connection user to Administrators group -->
            <principal>4d69eb9b-1111-1111-1111-5c3ad64cb6fd</principal>
        </group>
        <group id="Users">
            <principal>User@mail.com</principal>
        </group>
    </groups>
  <oauthSettings>
    <jwksUrl>https://login.microsoftonline.com/b41b72d0-1111-1111-1111-f949f367c91d/discovery/v2.0/keys</jwksUrl>
    <issuer>https://login.microsoftonline.com/b41b72d0-1111-1111-1111-f949f367c91d/v2.0</issuer>
        <!-- Same client id is used for WebAdmin master connection and users login -->
    <clientId>4d69eb9b-1111-1111-1111-5c3ad64cb6fd</clientId>
        <clientIdClaim>azp</clientIdClaim>
  </oauthSettings>
</config>
  1. In application.yaml, configure the Web Admin by filling the issuer-uri, security, and timebase branches:
...
# Add issuer
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: "https://login.microsoftonline.com/b41b72d0-1111-1111-1111-f949f367c91d/v2.0"
...
timebase:
  url: dxtick://localhost:8011
  enable-uac: true    # Enable TimeBase provided UAC
  # Configure master connection
  oauth2-client:
    url: https://login.microsoftonline.com/b41b72d0-1111-1111-1111-f949f367c91d/oauth2/v2.0/token
    client-id: 4d69eb9b-1111-1111-1111-5c3ad64cb6fd
    client-secret: <client secret>
    scope: "api%3A%2F%2Ffcf8a41f-1111-1111-1111-ec84d94df341%2F.default"
...
# Configure AzureAD SSO
security:
  oauth2:
    provider:
      providerType: SSO
      name: azure
      clientId: 4d69eb9b-1111-1111-1111-5c3ad64cb6fd
      validateIssuer: false
      usernameClaim: preferred_username
      scopes:
        - openid
        - profile
        - api://fcf8a41f-1111-1111-1111-ec84d94df341/app
    users:
      - username: User@mail.com
        authorities: [TB_ALLOW_READ, TB_ALLOW_WRITE]
...